Node / meshtastic / Meshtastic-Android / files / .github / agents / speckit.analyze.agent.md

Displaying Raw • View rendered • Download

---

Tc9d1d9description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.

Tc9d1d9---

Tc9d1d9## User Input

Ta5d6ff```Ta5d6fftext

$ARGUMENTS

Ta5d6ff```

You **MUST** consider the user input before proceeding (if not empty).

Tc9d1d9## Pre-Execution Checks

**Check for extension hooks (before analysis)**:

Tff7b72- Check if Ta5d6ff`.specify/extensions.yml` exists in the project root.

Tff7b72- If it exists, read it and look for entries under the Ta5d6ff`hooks.before_analyze` key

Tff7b72- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally

Tff7b72- Filter out hooks where Ta5d6ff`enabled` is explicitly Ta5d6ff`false`. Treat hooks without an Ta5d6ff`enabled` field as enabled by default.

Tff7b72- For each remaining hook, do **not** attempt to interpret or evaluate hook Ta5d6ff`condition` expressions:

Tff7b72- If the hook has no Ta5d6ff`condition` field, or it is null/empty, treat the hook as executable

Tff7b72- If the hook defines a non-empty Ta5d6ff`condition`, skip the hook and leave condition evaluation to the HookExecutor implementation

Tff7b72- For each executable hook, output the following based on its Ta5d6ff`optional` flag:

Tff7b72- **Optional hook** (Ta5d6ff`optional: true`):

Ta5d6ff ```

## Extension Hooks

**Optional Pre-Hook**: {extension}

Command: `/{command}`

Description: {description}

Prompt: {prompt}

To execute: `/{command}`

```

Tff7b72- **Mandatory hook** (Ta5d6ff`optional: false`):

Ta5d6ff ```

## Extension Hooks

**Automatic Pre-Hook**: {extension}

Executing: `/{command}`

EXECUTE_COMMAND: {command}

Wait for the result of the hook command before proceeding to the Goal.

```

Tff7b72- If no hooks are registered or Ta5d6ff`.specify/extensions.yml` does not exist, skip silently

Tc9d1d9## Goal

Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (Ta5d6ff`spec.md`, Ta5d6ff`plan.md`, Ta5d6ff`tasks.md`) before implementation. This command MUST run only after Ta5d6ff`/speckit.tasks` has successfully produced a complete Ta5d6ff`tasks.md`.

Tc9d1d9## Operating Constraints

**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).

**Constitution Authority**: The project constitution (Ta5d6ff`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside Ta5d6ff`/speckit.analyze`.

Tc9d1d9## Execution Steps

Tc9d1d9### 1. Initialize Analysis Context

Run Ta5d6ff`.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:

Tff7b72- SPEC = FEATURE_DIR/spec.md

Tff7b72- PLAN = FEATURE_DIR/plan.md

Tff7b72- TASKS = FEATURE_DIR/tasks.md

Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).

For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").

Tc9d1d9### 2. Load Artifacts (Progressive Disclosure)

Load only the minimal necessary context from each artifact:

**From spec.md:**

Tff7b72- Overview/Context

Tff7b72- Functional Requirements

Tff7b72- Success Criteria (measurable outcomes — e.g., performance, security, availability, user success, business impact)

Tff7b72- User Stories

Tff7b72- Edge Cases (if present)

**From plan.md:**

Tff7b72- Architecture/stack choices

Tff7b72- Data Model references

Tff7b72- Phases

Tff7b72- Technical constraints

**From tasks.md:**

Tff7b72- Task IDs

Tff7b72- Descriptions

Tff7b72- Phase grouping

Tff7b72- Parallel markers [P]

Tff7b72- Referenced file paths

**From constitution:**

Tff7b72- Load Ta5d6ff`.specify/memory/constitution.md` for principle validation

Tc9d1d9### 3. Build Semantic Models

Create internal representations (do not include raw artifacts in output):

Tff7b72- **Requirements inventory**: For each Functional Requirement (FR-###) and Success Criterion (SC-###), record a stable key. Use the explicit FR-/SC- identifier as the primary key when present, and optionally also derive an imperative-phrase slug for readability (e.g., "User can upload file" → Ta5d6ff`user-can-upload-file`). Include only Success Criteria items that require buildable work (e.g., load-testing infrastructure, security audit tooling), and exclude post-launch outcome metrics and business KPIs (e.g., "Reduce support tickets by 50%").

Tff7b72- **User story/action inventory**: Discrete user actions with acceptance criteria

Tff7b72- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)

Tff7b72- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements

Tc9d1d9### 4. Detection Passes (Token-Efficient Analysis)

Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.

Tc9d1d9#### A. Duplication Detection

Tff7b72- Identify near-duplicate requirements

Tff7b72- Mark lower-quality phrasing for consolidation

Tc9d1d9#### B. Ambiguity Detection

Tff7b72- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria

Tff7b72- Flag unresolved placeholders (TODO, TKTK, ???, Ta5d6ff`<placeholder>`, etc.)

Tc9d1d9#### C. Underspecification

Tff7b72- Requirements with verbs but missing object or measurable outcome

Tff7b72- User stories missing acceptance criteria alignment

Tff7b72- Tasks referencing files or components not defined in spec/plan

Tc9d1d9#### D. Constitution Alignment

Tff7b72- Any requirement or plan element conflicting with a MUST principle

Tff7b72- Missing mandated sections or quality gates from constitution

Tc9d1d9#### E. Coverage Gaps

Tff7b72- Requirements with zero associated tasks

Tff7b72- Tasks with no mapped requirement/story

Tff7b72- Success Criteria requiring buildable work (performance, security, availability) not reflected in tasks

Tc9d1d9#### F. Inconsistency

Tff7b72- Terminology drift (same concept named differently across files)

Tff7b72- Data entities referenced in plan but absent in spec (or vice versa)

Tff7b72- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)

Tff7b72- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)

Tc9d1d9### 5. Severity Assignment

Use this heuristic to prioritize findings:

Tff7b72- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality

Tff7b72- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion

Tff7b72- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case

Tff7b72- **LOW**: Style/wording improvements, minor redundancy not affecting execution order

Tc9d1d9### 6. Produce Compact Analysis Report

Output a Markdown report (no file writes) with the following structure:

Tc9d1d9## Specification Analysis Report

| ID | Category | Severity | Location(s) | Summary | Recommendation |

|----|----------|----------|-------------|---------|----------------|

| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |

(Add one row per finding; generate stable IDs prefixed by category initial.)

**Coverage Summary Table:**

| Requirement Key | Has Task? | Task IDs | Notes |

|-----------------|-----------|----------|-------|

**Constitution Alignment Issues:** (if any)

**Unmapped Tasks:** (if any)

**Metrics:**

Tff7b72- Total Requirements

Tff7b72- Total Tasks

Tff7b72- Coverage % (requirements with >=1 task)

Tff7b72- Ambiguity Count

Tff7b72- Duplication Count

Tff7b72- Critical Issues Count

Tc9d1d9### 7. Provide Next Actions

At end of report, output a concise Next Actions block:

Tff7b72- If CRITICAL issues exist: Recommend resolving before Ta5d6ff`/speckit.implement`

Tff7b72- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions

Tff7b72- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"

Tc9d1d9### 8. Offer Remediation

Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)

Tc9d1d9### 9. Check for extension hooks

After reporting, check if Ta5d6ff`.specify/extensions.yml` exists in the project root.

Tff7b72- If it exists, read it and look for entries under the Ta5d6ff`hooks.after_analyze` key

Tff7b72- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally

Tff7b72- Filter out hooks where Ta5d6ff`enabled` is explicitly Ta5d6ff`false`. Treat hooks without an Ta5d6ff`enabled` field as enabled by default.

Tff7b72- For each remaining hook, do **not** attempt to interpret or evaluate hook Ta5d6ff`condition` expressions:

Tff7b72- If the hook has no Ta5d6ff`condition` field, or it is null/empty, treat the hook as executable

Tff7b72- If the hook defines a non-empty Ta5d6ff`condition`, skip the hook and leave condition evaluation to the HookExecutor implementation

Tff7b72- For each executable hook, output the following based on its Ta5d6ff`optional` flag:

Tff7b72- **Optional hook** (Ta5d6ff`optional: true`):

Ta5d6ff ```

## Extension Hooks

**Optional Hook**: {extension}

Command: `/{command}`

Description: {description}

Prompt: {prompt}

To execute: `/{command}`

```

Tff7b72- **Mandatory hook** (Ta5d6ff`optional: false`):

Ta5d6ff ```

## Extension Hooks

**Automatic Hook**: {extension}

Executing: `/{command}`

EXECUTE_COMMAND: {command}

```

Tff7b72- If no hooks are registered or Ta5d6ff`.specify/extensions.yml` does not exist, skip silently

Tc9d1d9## Operating Principles

Tc9d1d9### Context Efficiency

Tff7b72- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation

Tff7b72- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis

Tff7b72- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow

Tff7b72- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts

Tc9d1d9### Analysis Guidelines

Tff7b72- **NEVER modify files** (this is read-only analysis)

Tff7b72- **NEVER hallucinate missing sections** (if absent, report them accurately)

Tff7b72- **Prioritize constitution violations** (these are always CRITICAL)

Tff7b72- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)

Tff7b72- **Report zero issues gracefully** (emit success report with coverage statistics)

Tc9d1d9## Context

$ARGUMENTS